ReplaceIndexedCollectionItemHdl

ReplaceIndexedCollectionItemHdl
Header:	Collections.h		Carbon status:	Supported

Replaces the variable-length data of an item in a collection given the item’s collection index, specifying the item’s new variable-length data using a handle rather than a pointer and a data size.

OSErr ReplaceIndexedCollectionItemHdl (
    Collection aCollection, 
    SInt32 index, 
    Handle itemData
);

aCollection: A reference to the collection containing the item you want to replace. The behavior of this function is undefined if you do not provide a reference to a valid collection object.
index: The collection index associated with the item you want to replace.
itemData: A Macintosh Memory Manager handle to the new variable-length data. This function copies the information referenced by the itemData parameter into the collection item; after calling this function, you may alter this information or free the memory referenced by this parameter without affecting the collection.

function result: A result code. If the aCollection collection does not contain an item whose collection index matches the value of the index parameter, this function returns a collectionIndexRangeErr result code.

DISCUSSION

If the aCollection collection does contain an item with the specified index, this function replaces the data in that item with new data (if the existing item is not locked—if it is, this function returns a collectionItemLockedErr result code). The resulting item contains

the same collection tag as the original item
the same collection ID as the original item
the same attributes as the original item
the variable-length data specified by the itemData parameter

To replace a collection item using a pointer (rather than a handle) to the item’s variable-length data, use the ReplaceIndexedCollectionItem function.

To replace a collection item using the item’s collection tag and collection ID (rather than the item’s collection index), use the AddCollectionItemHdl function.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.